Configuring API-level tracing

API-level tracing controls give administrators fine-grained authority over OpenTelemetry telemetry generation on deployed APIs. By selectively enabling tracing on mission-critical or troubleshooting-sensitive APIs and turning off tracing for high-volume or low-priority services, organizations can optimize observability backend costs while eliminating telemetry data noise.

Per-API tracing operates on an override hierarchy consisting of three operational choices: Basic, Intermediate, and Advanced, with Intermediate as the default state for every API. This allows individual services to diverge from the Gateway's global baseline as operational needs change. For instance, setting an API to Basic mode suppresses internal policy execution spans to save storage, but leaves root server and client spans intact to guarantee that distributed trace context headers (traceparent) continue propagating uninterrupted to downstream backends.

Administrative capabilities are governed by platform privileges. Users with edit access (API Management - APIs privilege) can modify tracing modes and parameters, whereas users with read-only privileges (API Management - Read APIs privilege) are restricted to viewing active configurations and monitoring live diagnostic sessions. Refer to API Management roles and privileges for which roles include each privilege.

Unlike global Gateway pipeline updates, per-API tracing adjustments take effect instantly on the active request path without requiring an API Gateway restart. However, per-API controls remain subordinate to global Gateway settings; when global Gateway tracing is inactive, all API-level toggles and controls are automatically locked and suppressed.

Configuration steps

Prerequisites

• Access to Boomi API Management with permissions to manage deployed APIs.
• OpenTelemetry must be enabled globally on the assigned API Gateway. If OTel is disabled on the Gateway, API-level tracing options will be hidden, and an informational banner will instruct you to configure Gateway Settings first.

Follow these steps to configure API-level tracing for a deployed API:

1. Log in to Boomi API Management.

2. Navigate to Manage APIs > Deployed APIs.

3. Select your deployed API and select Settings from the sub-menu.

4. In the left navigation sidebar, select API Tracing.

5. Verify your access level and Gateway status on the API Tracing screen:

   • Read-only access: If you hold the API Management - Read APIs privilege, a "Read only" badge appears next to the header, controls are disabled, and the Save button is hidden. You can still view active verbose session banners and countdown timers.
   • Gateway disabled state: If global Gateway tracing is off, click the Gateway Settings button on the informational banner to enable OTel globally first.

6. Under Tracing Mode, select one of the three operational choices based on your observability goals:

   • Basic: Select Basic to force tracing off for this specific API. This suppresses internal policy execution and content streaming spans while maintaining root server/client spans and downstream trace context propagation (traceparent headers).
   • Intermediate (default): Every API starts on Intermediate unless changed. It generates a single trace span per policy in execution sequence.

   Figure 2: Standard trace waterfall in New Relic displaying single sequential execution spans for each policy during Intermediate tracing mode.

   

   • Advanced: Select Advanced to capture deep diagnostic metadata across policy boundaries for time-limited troubleshooting sessions.

7. Select Save to apply your changes. The updated tracing configuration takes effect immediately on the runtime path without requiring a Gateway restart.

Policy span suppression mechanics in Basic mode

When an API is set to Basic mode, the Gateway enforces a strict suppression contract to eliminate unnecessary telemetry storage:

• Internal policy spans suppressed: All internal policy execution spans and policy content streaming spans are completely suppressed. Always-streaming policies (such as Groovy scripts) and scope-gated policies (such as JSON or XML threat protections) do not emit internal spans.
• Trace context propagation maintained: Choosing Basic mode controls what telemetry is recorded; it does not break trace context propagation. The root Gateway server span (span.kind=server) and outbound Gateway client span (span.kind=client) remain active, ensuring that distributed trace headers (traceparent) are passed intact to downstream integration runtimes and backend services.
• Outbound policy calls: Independent HTTP calls initiated directly by specialized policies (such as HTTP Callouts or Traffic Shadowing) generate external HTTP client spans via the Gateway network instrumenter and are tracked separately from internal policy spans.

Figure 1: Trace waterfall in New Relic for an API in Basic mode, showing root trace context propagation while suppressing internal policy execution spans.

Role-based access control (RBAC)

Editing API tracing settings requires administrative permissions:

• Read-only privilege (API Management - Read APIs): Users assigned read-only access will see a "Read only" badge next to the API Tracing section header. All radio buttons, checkboxes, and time range fields are disabled, and the Save button is completely hidden. Read-only users can still view active verbose session banners and live countdown timers.